COMMENT ⊗   VALID 00005 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	Guide to vision routines on [VIS,HPM]
C00010 00003	VIXHDR.SAI   for displaying grey scale and halftone pictures on data disc.
C00014 00004	FNTHDR.SAI   for inserting XGP font characters into pictures.
C00017 00005	Internal picture array format
C00019 ENDMK
C⊗;
Guide to vision routines on [VIS,HPM]

PIXHDR.SAI   utility routines for getting, saving, moving, etc. pictures

	requires: PIXFAI.REL,PIXSAI.REL

	provides:
		  PCLN,PCWD,PCBY,PCBYA,LNWD,LNBY,	where to find things in
		  LNBYA,WDBY,WDBI,BYBI,BPTAB,LINTAB	picture arrays


	VALUE  ←  PIXEL(PICTURE,ROW,COLUMN);		value of a particular pixel
        VALUE  ←  INTREL(PIC,ROW,COL);  interpolating PIXEL. ROW, COL, VALUE real.
		  PUTEL(PICTURE,ROW,COLUMN,VALUE);	change a pixel
		  ADDEL(PICTURE,ROW,COLUMN,VALUE);	increment a pixel
		  ADDIEL(PIC,ROW,COL,VAL); interpolating ADDEL. R, C, V real.

        SIZE   ←  PFLDIM(FILNAME);		size of array needed for pic file
        SIZE   ←  GETPFL(FILNAME,PICTURE);		read in a pic file
	SIZE   ←  GETPFD(FILNAME,DIM[0:10]);    read in parameters of picture
	CHAN   ←  OPNPFL(FILNAME,DIM[0:10]);    read in parameters of picture, and
          					open file for input, at 1st scanline
		  PUTPFL(PICTURE,FILENAME);		write out PICTURE

        SIZE   ←  PIXDIM(HEIGHT,WIDTH,BITS);	size of array for HxWxB picture
        SIZE   ←  MAKPIX(HEIGHT,WIDTH,BITS,PICTURE); make skeleton HxWxB picture
                  WIPE(PICTURE,VALU(0)); make every data word (not byte!) =VALU

                  pixtrn(src,tr,dest); transforms src into dst by array tr.
                     tr is a 3x3 real array. For all pixels (y,x) in dest
                     set (ty,tx,foo) ← (y,x,1) * transform. if (ty,tx) is
                     in src then dest(y,x) ← src(ty,tx);

		  COPPIC(PICTURE1,PICTURE2);  copy pic1 to pic2
                  TILE(PIC1,YL1,XL1, TY,TX, PIC2,YL2,XL2); take piece of size
			TYxTX at YL1,XL1 in PIC1, deposit at YL2,XL2 in PIC2
                  SQTILE(PIC1,YL1,XL1, TY,TX,YSQ,XSQ, PIC2,YL2,XL2);
			a TY*YSQ by TX*XSQ tile from PIC1 with upleft at YL1,XL1
			is squished into a TY by TX tile in PIC2, YL2,XL2 upleft
			The YSQ by XSQ areas in PIC1 are summed and scaled as needed
		  HAFPIC(PICTURE1,PICTURE2,MAXBIT);  reduce pic to half resolution
		  SHRINK(PICT1,PICT2);        squeeze or expand PICT1 into PICT2
			pixels are sampled, not interpolated or averaged.

                  PICADD(PICTURE,PICSUM);     add a picture to a picture
 		  PICSUB(PICA,PICDIFF);	      subtract. PICA-PICDIFF → PICDIFF
                  PICMUL(PICTURE,PICPRD);     multiply pictures. no bounds check.
		  PICSH(PIC1,PIC2,DIV);       every pixel in PIC1/DIV→PIC2

		  GRAY(PIC);	Convert to gray code.
		  UNGRAY(PIC);	Convert back.

        NRETRY ←  CAMPIX(CAMERA,YEDGE,XEDGE,PICTURE,
                    SUMS(1),BCLIP(7),TCLIP(0),MAXTRY(20)); read from a camera
        NRETRY ←  CLPADJ(CAM,BLCIP,TCLIP); find optimum clip levels for CAM
        NRETRY ←  TVSNAP(CAM,YEDG,XEDG,PIC,BCLIP,TCLIP,NTRY); primitive camera
        NRETRY ←  TVRAW(CAM,YEDG,XEDG,PIC,BCLIP,TCLIP,NTRY); routines, used by
                  TVBTMX(PIC4,PICN,XFRM,INHIBEQ);		     CAMPIX
                  TVBTMY(PIC4,PICN,XFRM,INHIBLE);
                  TVBTMZ(PIC4,PICN,XFRM,INHIBGE);

       SUM     ←  INTOP(PIC,WINSIZE,ANSARRY,YEDGE(0),XEDGE(0));interest operator
                  INTLOM(HIG,WID,ANSARRY); intop local max operator
       SIZE    ←  INTERESTDIM(PICTURE,WINDOWSIZE);  pic size needed for intrst op
		  INTEREST(PICTURE,WINDOW,RESULTPICTURE); make interest op picture

       BESTVAL ←  MATCH(PICTURE1,SY1,SX1,SY2,SX2, PICTURE2,DY1,DX1,DY2,DX2);
       BSTCOEF ←  NORCOR(PICTURE1,SY1,SX1,SY2,SX2, PICTURE2,DY1,DX1,DY2,DX2);
                   ;correlators, find Source window in pic1 in Dest in pic2

		  CLEAN(PICTURE);	remove single pixel noise, blurs a little
		  PASSHI(PICTURE1,WINDOWSIZE,PICTURE2);   high pass filter
		  LOWPAS(PICTURE);     in place low pass filter. 4 pxls → 1 pxl.
        SUM    ←  CMPPAR(PICTURE1,PICTURE2);  compare two pics [ sig(x-y)↑2 ]
        SUM    ←  CMPPAD(PICTURE1,PICTURE2);  quick and dirty compare

		  PERBIT(PICTURE, TRANSFORM); transform each pixel of pic
		  HISTOG(PICTURE, HISTOGRAM); count # of occurences of each gray val
		  ENHANCE(PICTURE);	      make histogram flat
		  SYNCHRONIZE(PICTURE1);      do a vertical roll fixup

		  ROWSUM(PICTURE1,ROWSUMS);   sum up the pixels in each row
		  ROWSUD(PICTURE1,ROWSUMS);   dirty rowsums, one pixel/word used
		  COLSUM(PICTURE1,COLSUMS);   sum up the pixels in each col
       LONG REAL← SUMSQR(PIC);		      double prec. sum of squares of pixels
	MASS	← CENTRO(PIC,YL,XL,YH,XH,THR); centroid and moment of a dark area

                  UNPACK(SOURCEARRAY, PICTURE);   copy a pict into a full wd array
		  GETPAR(ARRY, PICTR);	      copy full word array of pixels to pic

		  EDGEINIT(PICTURE,SIZE);	initialize edge operator
                  EDGE(X,Y,EDGERESULT);		apply edge operator

	NOTE: all picture and other arrays are zero origin in all dimensions
VIXHDR.SAI   for displaying grey scale and halftone pictures on data disc.
		an extension for the display routines in DDSUB.SAI[GRA,HPM]

	requires: PIXHDR.SAI[VIS],DDHDR.SAI[GRA],VIXFAI.REL[VIS],VIXSAI.REL[VIS]

	provides: VIDEO(X1,Y1,X2,Y2,PICTURE,BIT);
        	  VID(X1,Y1,X2,Y2,PICTURE,BIT);
			display PICTURE between X1,Y1,X2,Y2 in SCREEN
			co-ordinates. If BIT=-1 then a fast, low quality
			halftone, if -2 then a high quality halftone, if
			-3 then a buggy halftone. If positive then BIT
			represents a bit mask, which is anded with each
			pixel. If the result is nonzero, a bit is turned
			on in the corresponding part of the display.

		   VIDONE(PICTURE,BT,I(0),J(0));
			similar to VID but faster and simpler. Maps picture
			elements one to one to data disc points. Upper left
			corner of picture is placed I physical DD scanlines
			from the top of the picture, and indented J DD
			elements from the left. Complements the masked bit
			instead of setting it to one.

		   VIDFOR(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
			Like VIDONE, but for 4 bit pictures and four DD buffers.
			Sets up all buffers at once, clearing displayed area
			and inverting bits for compatibility with the inverted
			gray code produced by TVRAW.

		   VIDFRT(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
			Transposed VIDFOR, makes picture twice as wide on its side.

		   VIDFRX(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
			Like VIDFOR, but makes a picture twice as wide and tall.
			One picture pixel → 4 DD pixels.

		   VID1(PICTURE,BUF1,I(0),J(0));
		   VID3(PICTURE,BUF1,BUF2,BUF4,I(0),J(0));
		   VID4(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
		   VID5(PICTURE,BUF1,BUF2,BUF4,BUF8,BUF16,I(0),J(0));
			Like VIDFOR, for 1, 3, 4 and 5 bit pictures, but assumes
			normal gray code and produces a complemented display.

                   VIDXGP(PIC; I0,J0,PLEN);
			Send a picture to the XGP. Dumb thing to do except
			for one bit pictures.
FNTHDR.SAI   for inserting XGP font characters into pictures.

	requires: FNTFAI.REL[VIS],FNTSAI.REL[VIS]

		   FNTSEL(FNTNUM,FILSPEC,FNTHEAD);
			define font number FNTNUM to be font FILSPEC.
			FNTHEAD is the first word of an array '204 words
			long which must be reserved for this font.

		   CHRDEP(FNTNUM,CHR,PIC,YLO,XLO,YCOMP,XCOMP);
			add character CHR to the picture PIC in font # FNTNUM
			starting at position YLO, XLO
			compressed by YCOMP in Y and XCOMP in X.

		   CHRPED(FNTNUM,CHR,PIC,YLO,XLO,YCOMP,XCOMP);
			add CHR to PIC, sideways, writing bottom to top.
			X and Y positions and compressions refer to text,
			not picture, reference system.

		   CHR3X2(FNTNUM,CHR,PIC,YLO,XLO);
			like CHRDEP, but compresses X by 3 and Y by 2, and
			goes faster

		   CHR6X4(FNTNUM,CHR,PIC,YLO,XLO);
			like CHRDEP, but compresses X by 6 and Y by 4, and
			goes faster

		   CHR3Y4(FNTNUM,CHR,PIC,YLO,XLO);
			like CHRPED, but compresses X by 3 and Y by 4, and
			goes faster

		   FCACHE(BUFFER,BUFSIZ);
			set up a buffer for caching letter descriptions.
			Doing this greatly speeds up CHRDEP. 5 or 10 K
			is a good buffer size.

		  Defines FNTHIG, position in FNTHEAD where height is stored,
                  and FNTBAS, where baseline is stored.
Internal picture array format

	WORD		CONTENTS
	
	0		PCLN   number of scanlines in the picture
	1		PCWD   words in the pixel portion of the picture
	2		PCBY   valid bytes in the picture
	3		PCBYA  bytes in the picture, including null
				bytes at end of each scanline

	4		LNWD   words per scanline
	5		LNBY   valid bytes per scanline
	6		LNBYA  bytes per scanline, including the nulls

	7		WDBY   bytes per word
	8		WDBI   bits in the valid portion of each word

	9		BYBI   bits per byte

	10		BMAX   2↑BYBI-1, the maximum value of a byte

	11		BPTAB  address of SECOND entry in byte pointer
				table 12+PCLN+address of array

	12 to 11+PCLN	LINTAB table containg the actual address of the first
				word of each scanline, in obvious order

	12+PCLN to 	table containing byte pointers to samples within
	 12+PCLN+LNBYA		lines, to be added to line address.
				The first entry, when ILDB'ed causes
				loading of the first byte in the line.

	13+PCLN+LNBYA to	the picture
	 12+PCLN+LNBYA+PCWD